Paddle Billing
Search

Create and issue an invoice

Create invoices as part of a sales-assisted billing process using manually-collected transactions. Paddle automatically creates a subscription for you once an invoice is issued.

Invoices let you offer sales-assisted billing. Your sales team can draft and send invoices for subscriptions, collecting payment manually rather than by charging a card on file.

They're generally used for bigger-dollar deals, like enterprise plans, and might include one-time or recurring fees for things like implementation or support.

Illustration of an invoice from Paddle

How it works

When customers sign up and pay for a subscription using Paddle Checkout, Paddle collects using an automatically-collected transaction and creates a subscription where the collection mode is automatic. This means that Paddle saves the payment method used and uses it to collect for future renewals and charges.

Invoices work using manually-collected transactions. This means that Paddle sends an invoice that customers must pay themselves by bank or wire transfer or using Paddle Checkout. Paddle creates a subscription when an invoice is issued, and future renewals and charges send new invoices that the customer must pay manually.

Invoice lifecycle

Transaction statuses mirror the invoice lifecycle:

  1. Draft your invoice

    When you create an invoice (manually-collected transaction) initially, it's a draft. You can work through changes with the customer, adding or removing items as you scope out their requirements. Draft invoices may have the status draft or ready. They're ready when they have all the required fields to be issued.

  2. Issue your invoice

    When you and the customer are happy with an invoice (manually-collected transaction), you can issue it by marking the transaction as billed. At this point, it's issued an invoice number and becomes a financial record. Paddle automatically sends a copy to your customer and creates a subscription for them. In Paddle, it has the status of billed.

  3. Payment received

    When the customer pays an invoice (manually-collected transaction), Paddle automatically handles reconciliation and marks the invoice as paid. In Paddle, its status is completed.

Payments, including failed payment attempts, are logged against a transaction. Customers can pay invoices by bank or wire transfer, or you can turn Paddle Checkout for an invoice to let customers pay using card, digital wallet, or a local payment method. This is especially handy for lower-value changes, like adding users or modules mid-cycle.

This guide focuses on creating manually-collected transactions. You can also create automatically-collected transactions, then pass them to Paddle.js to open a checkout for the items on them.

Before you begin

Set your default payment link

Invoices work using manually-collected transactions. Transactions may include a link to pay using Paddle Checkout, so to create a transaction you'll need to:

  • Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
  • Get your default payment link domain approved, if you're working with the live environment.

We recommend starting the domain approval early in your integration process, so your domains are approved for when you're ready to go live.

Create customers

If you're working with the Paddle dashboard, you can create all the entities that you'll be working with as you create your invoice (manually-collected transaction).

If you're working with the API, you'll need to:

Create products and prices

Transactions work with products and prices to say what you're billing for, so you'll also need to create a product and a related price to bill for an item in your catalog.

You can also add custom items to an invoice to bill for them. Custom items are one-off or bespoke items that are specific to that transaction. They're not part of your product catalog.

Create a draft invoice

To create an invoice, create a transaction with the collection_mode set to manual.

Manually-collected transactions have the status of either draft or ready when you first create them. They're draft draft while they're missing items, customer_id, and address_id, and they automatically change to ready when you add those fields.

Create an invoice using the API in two steps:

  1. Build request

    Build a request with information about who your invoice is for and what you're billing for.

  2. Create your invoice

    Send the request to create your invoice. Paddle creates it. Its status is draft or ready depending on the information you supplied.

Build request

Build an array of items, with an object containing either:

  • An item from your catalog

    Include a price ID and quantity for each item.

  • A custom item

    Include a price object and quantity for each item.

Custom items are one-off or bespoke items that are specific to that transaction. For example, you may agree a custom price with an enterprise customer at renewal. See: Work with custom items

Recurring items on a transaction must have the same billing interval. For example, you can't have a transaction with some prices that are billed monthly and some products that are billed annually.

itemsarray[object]

List of items to charge for.

quantityinteger

Quantity of this item on the transaction.

price_idstring

Paddle ID of an existing catalog price to add to this transaction, prefixed with pri_.

Set collection_mode to manual and include a billing_details object with invoicing-related information, like purchase order number and payment terms.

If collection_mode is omitted, Paddle creates an automatically-collected transaction.

collection_modestring

How payment is collected. automatic for checkout, manual for invoices.

billing_detailsobject

Details for invoicing. Required if collection_mode is manual.

enable_checkoutboolean

Whether the related transaction may be paid using a Paddle Checkout. If omitted when creating a transaction, defaults to false.

purchase_order_numberstring

Customer purchase order number. Appears on invoice documents.

additional_informationstring or null

Notes or other information to include on this invoice. Appears on invoice documents.

payment_termsobject

How long a customer has to pay this invoice once issued.

Include customer_id and address_id to say who this invoice is for.

If you're working with a business, include business_id too.

Transactions are automatically marked as ready when they have customer_id, address_id, and items. This means that they're ready to be issued (marked as billed).

customer_idstring

Paddle ID of the customer that this invoice is for, prefixed with ctm_.

address_idstring

Paddle ID of the address that this invoice is for, prefixed with add_.

business_idstring

Paddle ID of the business that this invoice is for, prefixed with biz_.

Request

This example creates a draft invoice for a 50-user enterprise plan with two additional products. It includes a customer and an address.

Send request

Send a POST request to the /transactions endpoint with the request you built.

POSThttps://api.paddle.com/transactions

Response

If successful, Paddle responds with a copy of the new transaction entity.

The created invoice is ready, since it includes all the required fields for it to be issued.

Update a draft invoice

While transactions are draft or ready, they don't have invoice numbers and aren't considered financial records yet. This means that you can make changes to the transaction and its items.

Update an invoice using the API in two steps:

  1. Build request

    Build a request with information about who your invoice is for and what you're billing for. If you're adding new items, your request should include any existing items that you'd like to keep.

  2. Update your invoice

    Send the request to update your invoice. Paddle updates it.

Build request

Build a request with any data that you'd like to change. You can change any writeable fields at this point, including address, customer, and items. It's common to make changes to items as you work with the customer.

When working with items, you should send the complete list of items that you'd like to be against your invoice — including any existing items. If you omit an item, it's removed from the items list. See: Work with lists

Request

Update invoice

Send a PATCH request to the /transactions/{transaction_id} endpoint with the request you built.

Issue an invoice

When you're happy with an invoice, issue it to mark it as finalized. At this point, it becomes a financial record so you can't make changes to it. It gets an invoice number and is sent to the customer.

You can create a transaction and mark it as billed by including "status": "billed" in your request to create or update, along with the other required fields — no need to make a separate request.

Issue an invoice using the API in two steps:

  1. Build request

    Build a request that sets status to billed. Transaction must be ready.

  2. Issue your invoice

    Send the request to issue your invoice. Its status changes to billed.

Transactions are financial records. You can't edit them if they're billed, canceled, or completed. Cancel a transaction and create another or create an adjustment if you need to make changes to a billed or completed transaction.

Build request

To issue an invoice, change the status of a manually-collected transaction to billed.

Paddle automatically assigns an invoice number and creates a related subscription when you send your request.

statusstring

Status of this transaction. You may set a transaction to billed or canceled, other statuses are set automatically by Paddle. Automatically-collected transactions may return completed if payment is captured successfully, or past_due if payment failed.

Request

This examples issues an invoice by changing the status to billed.

Issue your invoice

Send a PATCH request to the /transactions/{transaction_id} endpoint with the request you built.

Response

If successful, Paddle responds with a copy of the updated transaction entity with the status of billed.

At this point:

  • Paddle issues it an invoice number (invoice_number)
  • A copy is sent to the customer and any contacts against the related business
  • Paddle creates a related subscription if there are recurring products on this invoice (subscription_id)

invoice_number and subscription_id are added to a transaction asynchronously as part of completed transaction processing. They may not be returned in your request. Send a follow-up request to get the transaction, or listen for the transaction.completed webhook.

Get created subscription

Paddle automatically creates a subscription when you issue an invoice for recurring items. This lets you provision your app for the customer right away, rather than waiting for payment to complete. This is especially important when working with high-value invoices where payment is by wire transfer.

Events

  • subscription.created

    If you've subscribed to a webhook for subscription.created, you'll get a notification that includes the id of the new subscription. Use the transaction_id against the subscription.created notification to match to the correct transaction.

  • transaction.updated

    After subscription.created occurs, Paddle updates the transaction with the created subscription_id and transaction.updated occurs. Use subscription_id against the transaction.updated notification to get the related subscription.

API

Use the subscription_id against the transaction you just marked as billed to find the new subscription. Subscriptions are created asynchronously after a transaction is billed, so this may not be present in the initial response.

  1. Send a GET request to the /transactions/{transaction_id} endpoint, using the transaction_id of the manually-collected transaction you marked as billed.

  2. Extract the subscription_id from the response.

  3. Send a GET request to the /subscriptions/{subscription_id} endpoint, using the subscription_id you just extracted.

Events

transaction.createdOccurs when a transaction is first created.
transaction.updatedOccurs when a transaction is updated. This includes updates made by you, as well as system updates by Paddle.
transaction.readyOccurs when a transaction has all of the required fields to be marked as billed.
transaction.billedOccurs when a transaction is billed (invoice issued). Paddle issues an invoice number and it's considered final.
subscription.createdOccurs when a subscription is created as a result of a transaction being billed.
subscription.activatedOccurs when a subscription is activated as a result of a transaction being billed. This means any trial period has elapsed.

Related pages